---
title: Aggregations
---
<h2>{{ page.title }}</h2>

<p>
  An aggregation is responsible for providing analysis of a larger dataset, to make it more manageable.
  While it would be possible to plot millions of samples in a single graph, it is simply not practical.
  Aggregations give the mean to further aggregate the samples stored in the database.
</p>

<p>
  An aggregation can be defined either in JSON, or HQL.
  For each aggregation, both forms will be displayed below.
</p>

<ul>
  <li><a href="#average">Average Aggregation</a></li>
  <li><a href="#chain">Chain Aggregation</a></li>
  <li><a href="#count">Count Aggregation</a></li>
  <li><a href="#delta">Delta Aggregation</a></li>
  <li><a href="#deltapersec">Delta per Second Aggregation</a></li>
  <li><a href="#ratepersec">Rate per Second Aggregation</a></li>
  <li><a href="#max">Maximum Aggregation</a></li>
  <li><a href="#min">Minimum Aggregation</a></li>
  <li><a href="#notneg">Not Negative Aggregation</a></li>
  <li><a href="#stddev">Standard Deviation Aggregation</a></li>
  <li><a href="#sum">Sum Aggregation</a></li>
  <li><a href="#sum2">Sum Squared Aggregation</a></li>
  <li><a href="#filtering">TopK/BottomK/AboveK/BelowK Aggregation</a></li>
  <li><a href="#points">Points Above/Below Aggregation</a></li>
</ul>

<h3>Size and Extent</h3>

<p>
  The <em>size</em> of an aggregation determines the frequency that data occurs in the resulting aggregation.
  So a size of <em>two minutes</em> would cause an aggregation to output a series that has a sample, every two minutes.
</p>

<p>
  The <em>extent</em> of an aggregation determines how wide a single sample will load data in time.
  So an extent of <em>one hour</em> would cause each sample to be the result of aggregating the last hour of data.
</p>

<p>
  Combining <em>size</em> and <em>extent</em>, we now have a flexible system for describing how to build a dataset suitable for plotting.
</p>

<p>
The following graphics represents what data will be sampled to generate the sample at point <code>2</code>.
  <span style="color: #648cff">The blue bar</span> is the <em>extent</em>, and <span style="color: #ff8282;">the red bar</span> is the <em>size</em>.
</p>

<img style="width: 100%;" src="{{ 'images/size_extent.svg' | relative_url }}"></img>

<p>
  The next point we'll sample for is <code>3</code>.
  This applies the same principle as above.
</p>

<img style="width: 100%;" src="{{ 'images/size_extent_3.svg' | relative_url }}"></img>

<h3>Aggregating on Resource Identifiers</h3>

<p>
Resource Identifiers are not currently included in the Suggest index, and thus do not appear in suggestions.
Resource Identifiers can still be used in aggregations by adding them free-form.
</p>

<h3 id="average">
  Average Aggregation
  <a class="link-to" href="#average"><span class="glyphicon glyphicon-link"></span></a>
</h3>

<h5>JSON</h5>

<pre><code class="language-json">
{"type": "average", "sampling": {"unit": &lt;unit&gt;, "value": &lt;number&gt;}}
</code></pre>

<h5>HQL</h5>

<pre><code class="language-hql">
average(size=&lt;duration&gt;)
</code></pre>

<h5>Description</h5>

<p>
  The average aggregation takes all samples in a given extent, and calculates the average value over them.
</p>

<h3 id="chain">
  Chain Aggregation
  <a class="link-to" href="#chain"><span class="glyphicon glyphicon-link"></span></a>
</h3>

<h5>JSON</h5>

<pre><code class="language-json">
{"type": "chain", "chain": [&lt;aggregation&gt;, ..]}
</code></pre>

<h5>HQL</h5>

<pre><code class="language-hql">
&lt;aggregation&gt; | ..
</code></pre>

<h5>Description</h5>

<p>
  A chain aggregation applies the specified aggregations in order.
  The result of the first aggregation is fed into the second, and so forth.
</p>

<h3 id="count">
  Count Aggregation
  <a class="link-to" href="#count"><span class="glyphicon glyphicon-link"></span></a>
</h3>

<h5>JSON</h5>

<pre><code class="language-json">
{"type": "count", "sampling": {"unit": &lt;unit&gt;, "value": &lt;number&gt;}}
</code></pre>

<h5>HQL</h5>

<pre><code class="language-hql">
count(size=&lt;duration&gt;)
</code></pre>

<h5>Description</h5>

<p>
  The count aggregation calculates the number of all samples in a given extent.
</p>


<h3 id="delta">
  Delta Aggregation
  <a class="link-to" href="#delta"><span class="glyphicon glyphicon-link"></span></a>
</h3>

<h5>JSON</h5>

<pre><code class="language-json">
{"type": "delta"}
</code></pre>

<h5>HQL</h5>

<pre><code class="language-hql">
delta()
</code></pre>

<h5>Description</h5>

<p>
  The delta aggregation calculates the difference between samples in a given extent.<br /><br />

  It's intended to be used with gauges and can produce negative values.
</p>


<h3 id="deltapersec">
  Delta per Second Aggregation
  <a class="link-to" href="#deltapersec"><span class="glyphicon glyphicon-link"></span></a>
</h3>

<h5>JSON</h5>

<pre><code class="language-json">
{"type": "deltaPerSecond"}
</code></pre>

<h5>HQL</h5>

<pre><code class="language-hql">
deltaPerSecond()
</code></pre>

<h5>Description</h5>

<p>
  The delta per second aggregation calculates the difference per second between samples in a given extent.<br /><br />

  It's intended to be used with gauges and can produce negative values.
</p>

<h3 id="ratepersec">
  Rate per Second Aggregation
  <a class="link-to" href="#ratepersec"><span class="glyphicon glyphicon-link"></span></a>
</h3>

<h5>JSON</h5>

<pre><code class="language-json">
{"type": "ratePerSecond", "sampling": {"unit": &lt;unit&gt;, "value": &lt;number&gt;}}
</code></pre>

<h5>HQL</h5>

<pre><code class="language-hql">
ratePerSecond()
</code></pre>

<h5>Description</h5>

<p>
  The rate per second aggregation calculates the rate per second between samples in a given extent.<br /><br />

  Rate per second works with sampling. If a queries resolution is 1 minute and points are published
  every 30s each bucket will contain 2 points. The rate will be calculated by getting the difference
  between the two points values and dividing them by the time between the points.<br /><br />

  Note: at least 2 points are required in order to calculate the rate. Otherwise the previous value
  is unknown.<br /><br />

  It's intended to be used with cumulative counters. It will handle the counters being reset because
  of restarts, etc.
</p>


<h3 id="max">
  Max Aggregation
  <a class="link-to" href="#max"><span class="glyphicon glyphicon-link"></span></a>
</h3>

<h5>JSON</h5>

<pre><code class="language-json">
{"type": "max", "sampling": {"unit": &lt;unit&gt;, "value": &lt;number&gt;}}
</code></pre>

<h5>HQL</h5>

<pre><code class="language-hql">
max(size=&lt;duration&gt;)
</code></pre>

<h5>Description</h5>

<p>
  The max aggregation picks the <em>largest</em> numerical value seen in the given extent.
</p>


<h3 id="min">
  Min Aggregation
  <a class="link-to" href="#min"><span class="glyphicon glyphicon-link"></span></a>
</h3>

<h5>JSON</h5>

<pre><code class="language-json">
{"type": "min", "sampling": {"unit": &lt;unit&gt;, "value": &lt;number&gt;}}
</code></pre>

<h5>HQL</h5>

<pre><code class="language-hql">
min(size=&lt;duration&gt;)
</code></pre>

<h5>Description</h5>

<p>
  The min aggregation picks the <em>smallest</em> numerical value seen in the given extent.
</p>


<h3 id="notneg">
  Not Negative Aggregation
  <a class="link-to" href="#notneg"><span class="glyphicon glyphicon-link"></span></a>
</h3>

<h5>JSON</h5>

<pre><code class="language-json">
{"type": "notNegative"}
</code></pre>

<h5>HQL</h5>

<pre><code class="language-hql">
notNegative()
</code></pre>

<h5>Description</h5>

<p>
  The not negative aggregation filters out negative values from all samples in a given extent.
</p>


<h3 id="stddev">
  Standard Deviation Aggregation
  <a class="link-to" href="#stddev"><span class="glyphicon glyphicon-link"></span></a>
</h3>

<h5>JSON</h5>

<pre><code class="language-json">
{"type": "stddev", "sampling": {"unit": &lt;unit&gt;, "value": &lt;number&gt;}}
</code></pre>

<h5>HQL</h5>

<pre><code class="language-hql">
stddev(size=&lt;duration&gt;)
</code></pre>

<h5>Description</h5>

<p>
  The standard deviation aggregation calculates the standard deviation of all samples in a given extent.
</p>


<h3 id="sum">
  Sum Aggregation
  <a class="link-to" href="#sum"><span class="glyphicon glyphicon-link"></span></a>
</h3>

<h5>JSON</h5>

<pre><code class="language-json">
{"type": "sum", "sampling": {"unit": &lt;unit&gt;, "value": &lt;number&gt;}}
</code></pre>

<h5>HQL</h5>

<pre><code class="language-hql">
sum(size=&lt;duration&gt;)
</code></pre>

<h5>Description</h5>

<p>
  The sum aggregation sums the values of all points in a given extent.
</p>


<h3 id="sum2">
  Sum Squared Aggregation
  <a class="link-to" href="#sum2"><span class="glyphicon glyphicon-link"></span></a>
</h3>

<h5>JSON</h5>

<pre><code class="language-json">
{"type": "sum2", "sampling": {"unit": &lt;unit&gt;, "value": &lt;number&gt;}}
</code></pre>

<h5>HQL</h5>

<pre><code class="language-hql">
sum2(size=&lt;duration&gt;)
</code></pre>

<h5>Description</h5>

<p>
  The sum squared aggregation sums the squared values of all points in a given extent.
</p>

<h3 id="filtering">
  TopK/BottomK/AboveK/BelowK Aggregation
  <a class="link-to" href="#filtering"><span class="glyphicon glyphicon-link"></span></a>
</h3>

<h5>JSON</h5>

<pre><code class="language-json">
{"type": "topk", "k": &lt;number&gt;}
{"type": "bottomk", "k": &lt;number&gt;}
{"type": "abovek", "k": &lt;number&gt;}
{"type": "belowk", "k": &lt;number&gt;}
</code></pre>

<h5>HQL</h5>

<pre><code class="language-hql">
topk(&lt;number&gt;)
bottomk(&lt;number&gt;)
abovek(&lt;number&gt;)
belowk(&lt;number&gt;)
</code></pre>

<p>
  These are a set of filtering aggregations.
  A filtering aggregation reduces the number of result groups according to some
  criteria.
</p>

<ul>
  <li>TopK - Picks the largest time series</li>
  <li>BottomK - Picks the smallest time series</li>
  <li>AboveK - Picks the time series that has values above the given threshold</li>
  <li>BelowK - Picks the time series that has values below the given threshold</li>
</ul>


<h3 id="points">
  Points Above/Below Aggregation
  <a class="link-to" href="#points"><span class="glyphicon glyphicon-link"></span></a>
</h3>

<h5>JSON</h5>

<pre><code class="language-json">
{"type": "pointsabove", "threshold": &lt;number&gt;}
{"type": "pointsbelow", "threshold": &lt;number&gt;}
</code></pre>

<pre><code class="language-hql">
pointsabove(&lt;number&gt;)
pointsbelow(&lt;number&gt;)
</code></pre>

<p>
  These aggregations reduce the number of datapoints returned per series. Only datapoints
  matching the criteria will be returned, all others will be dropped.
</p>

<ul>
  <li>PointsAbove - Return only datapoints above the given threshold</li>
  <li>PointsBelow - Return only datapoints below the given threshold</li>
</ul>
